package org.broadway.monitor.dsl;

import org.broadway.interfaces.Action;
import org.broadway.interfaces.ObservedResource;
import org.broadway.monitor.Monitor;

/***
 * <p>
 * The MonitorDsl interface is intended to provide a mechanism to
 * create a Domain Specific Language to programmatically create monitors.
 * The DSL provides access to a more expressive syntax rather then the 
 * traditional procedural approach.
 * </p>
 * The intended usage is as follows:
 * <pre>
  * MonitorDsl(Monitor)
 * 	.observe(ObservedResource)
 * 	.observe(ObservedResource)
 * 	.forCondition(Conditional)
 *  .execute(Action);
 * </pre>
 * <p>
 * Using the DSL is a bit more restrictive than using the procedural
 * methods provided.  So, if you need to customize your monitor's behavior,
 * you may have to use the traditional procedural methods.
 * </p>
 * @author vladimir vivien
 * @see Monitor
 * @see ObservedObject
 * @see Conditional
 */
public interface MonitorDsl {
	/***
	 * Implement this method to add objects that will be observed.
	 * @param res - the resource which is being monitored.
	 * @return MonitorDsl
	 */
	public MonitorDsl observe(ObservedResource res);
	
	/**
	 * Impement this method to establish the conditional that will
	 * be evaluated to determine execution of an action.
	 * @param condition - A conditional object used to capture an evaluated expression.
	 * @return MonitorDsl
	 * @see Conditional
	 */
	public MonitorDsl forCondition(Conditional condition);
	
	/***
	 * This is the stopping method for the dsl statements
	 * for the monitor. When this is called, it will execute the 
	 * specified action and returns result object generated during
	 * execution.
	 * @param action - the action to execute for the conditional.
	 * @return - the result generated by the execution.
	 */
	public Object execute(Action action);
}
